HAL I3C migration: List of applicable concepts

This section provides information about the HAL I3C applicable architecture concepts.

Concepts for I3C

Concept	Description
Separation of initialization and configuration functions	The initialization has been split into three levels of functions: HAL_I3C_Init: initializes the handle and links it to an I3C instance. HAL_I3C_CTRL_SetConfig: configures the communication mode when operating in controller mode. HAL_I3C_TGT_SetConfig: configures the communication mode when operating in target mode.
Removal and conversion of init structure to configuration structure	The initialization structure has been removed and replaced by the configuration structures hal_i3c_ctrl_config_t and hal_i3c_tgt_config_t.
Renaming of the handle structure	The handle structure has been renamed to hal_i3c_handle_t.
Renaming unitary init structures	The structure I3C_InitTypeDef is no longer available, it is replaced by hal_i3c_ctrl_config_t and hal_i3c_tgt_config_t.
Remove MspInit and MspDeInit callbacks	HAL_I3C_MspInit and HAL_I3C_MspDeInit are no longer available they are replaced by a user sequence to initializes and configures the I3C.
Unitary configuration APIs	New APIs are available to get and set I3C features.
Dedicated DMA link APIs replace generic __HAL_LINKDMA macro	The __HAL_LINKDMA macro is no longer provided and new functions HAL_I3C_SetTxDMA() and HAL_I3C_SetRxDMA() are available to link a I3C HAL handle to a DMA HAL handle.
Introduction of HAL user data set/get APIs	Two functions to set and get user data are available: HAL_I3C_SetUserData and HAL_I3C_GetUserData.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each I3C event. These functions are used to register callback functions for different I3C events.
Introduce specialized IRQ handlers	HAL_I3C_ER_IRQHandler and HAL_I3C_EV_IRQHandler are still available in HAL2.
HAL implementation with LL inline functions	HAL I3C APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL I3C define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL I3C driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The I3C state machine is reworked to ensure transitions of the peripheral functional states.
Revised and optimized HAL API status returns	The HAL I3C functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation.
Revised and optimized HAL error management	Involves redesigning the error handling mechanisms within the HAL to improve the detection, reporting, and handling of errors.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL I3C driver have been removed and replaced by _t.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using ASSERT_DBG_STATE and ASSERT_DBG_PARAM macro.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL I3C header file remains and all macros, define statements, and functions from hal_i3c_ex.h have been moved to hal_i3c.h.
Provide RTOS-compatible acquire/release bus services for communication peripheral drivers.	New functions, HAL_I3C_AcquireBus() and HAL_I3C_ReleaseBus(), are provided to allow the acquisition and release of a HAL I3C handle, ensuring protection throughout a complete sequence.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including I3C instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL I3C functions start with HAL_I3C. All HAL I3C enumerations and structures start with hal_i3c.

Other HAL I3C changes

Concept	Consideration
Rationalize operational functions	All transfer operations, including single and multiple CCC transfers, can now be performed using the same transfer functions for polling, interrupt, and DMA modes. The following APIs: HAL_I3C_Ctrl_TransmitCCC, HAL_I3C_Ctrl_TransmitCCC_IT, HAL_I3C_Ctrl_TransmitCCC_DMA, HAL_I3C_Ctrl_ReceiveCCC, HAL_I3C_Ctrl_ReceiveCCC_IT, HAL_I3C_Ctrl_ReceiveCCC_DMA, HAL_I3C_Ctrl_Transmit, HAL_I3C_Ctrl_Transmit_IT, HAL_I3C_Ctrl_Transmit_DMA, HAL_I3C_Ctrl_Receive, HAL_I3C_Ctrl_Receive_IT, HAL_I3C_Ctrl_Receive_DMA, HAL_I3C_Ctrl_MultipleTransfer_IT, HAL_I3C_Ctrl_MultipleTransfer_DMA have been replaced by: HAL_I3C_CTRL_Transfer, HAL_I3C_CTRL_Transfer_IT, and HAL_I3C_CTRL_Transfer_DMA.
Add an interface to help the application retrieve the number of data received on the target side	At the end of a transfer, the application needs to know the size of the data received or transmitted on the target side. This can be done using the API: HAL_I3C_TGT_GetDataCounter.
Add an interface to manage specific sequences	Introduce a dedicated interface to stop SCL toggling in an infinite loop until a target responds, via the HAL_I3C_CTRL_RecoverSCLToIDLE API.
The function HAL_I3C_AddDescToFrame is replaced by multiple APIs	The frame formatting and building APIs is reworked to rely on building a transfer context, which is then submitted to the transfer start function. The HAL_I3C_AddDescToFrame API has been replaced by the following functions: HAL_I3C_CTRL_InitXferCtxCtrl, HAL_I3C_CTRL_InitXferCtxTx, HAL_I3C_CTRL_InitXferCtxRx, HAL_I3C_CTRL_BuildXferCtxPrivate, and HAL_I3C_CTRL_BuildXferCtxCCC.